openapi: 3.0.0
info:
  version: 1.0.0
  title: orb-fleet
servers:
  - url: 'http://localhost:8203'
paths:
  /agent_groups:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    get:
      summary: 'List current Agent Groups'
      operationId: listAgentGroups
      tags:
        - agent_groups
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Name"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/Direction"
        - $ref: "#/components/parameters/Tags"
      responses:
        '200':
          $ref: "#/components/responses/AgentGroupsPageRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
    post:
      summary: 'Create a new Agent Group'
      operationId: createAgentGroup
      tags:
        - agent_groups
      requestBody:
        $ref: "#/components/requestBodies/AgentGroupCreateReq"
      responses:
        '201':
          $ref: "#/components/responses/AgentGroupObjRes"
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '409':
          description: Entity already exist.
        '415':
          description: Missing or invalid content type.
        '422':
          description: Database can't process request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agent_groups/{id}:
    parameters:
      - $ref: "#/components/parameters/Authorization"
      - $ref: "#/components/parameters/AgentGroupId"
    get:
      summary: 'Get an existing Agent Group'
      operationId: readAgentGroup
      tags:
        - agent_groups
      responses:
        '200':
          $ref: "#/components/responses/AgentGroupObjRes"
        '400':
          description: Failed due to malformed JSON.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
    put:
      summary: 'Update an existing Agent Group'
      operationId: updateAgentGroup
      tags:
        - agent_groups
      requestBody:
        required: true
        $ref: "#/components/requestBodies/AgentGroupUpdateReq"
      responses:
        '200':
          $ref: "#/components/responses/AgentGroupObjRes"
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '422':
          description: Database can't process request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
    delete:
      summary: 'Delete an existing Agent Group'
      operationId: deleteAgentGroup
      tags:
        - agent_groups
      responses:
        '204':
          description: AgentGroup removed.
        '400':
          description: Failed due to malformed AgentGroup ID.
        '401':
          description: Missing or invalid access token provided.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agent_groups/validate:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    post:
      summary: 'Validate an Agent Group configuration without saving it'
      operationId: validateAgentGroup
      tags:
        - agent_groups
      requestBody:
        $ref: "#/components/requestBodies/AgentGroupCreateReq"
      responses:
        '200':
          $ref: "#/components/responses/AgentGroupValidateObjRes"
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '415':
          description: Missing or invalid content type.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"

  /agents:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    get:
      summary: 'List current Agents'
      operationId: listAgents
      tags:
        - agents
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Name"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/Direction"
        - $ref: "#/components/parameters/Tags"
      responses:
        '200':
          $ref: "#/components/responses/AgentPageRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
    post:
      parameters:
        - $ref: "#/components/parameters/Authorization"
      summary: 'Create a new Agent'
      operationId: createAgent
      tags:
        - agents
      requestBody:
        $ref: "#/components/requestBodies/AgentCreateReq"
      responses:
        '201':
          $ref: "#/components/responses/AgentObjRes"
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '409':
          description: Entity already exist.
        '415':
          description: Missing or invalid content type.
        '422':
          description: Database can't process request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agents/{id}:
    parameters:
      - $ref: "#/components/parameters/Authorization"
      - $ref: "#/components/parameters/AgentId"
    get:
      summary: 'Get an existing Agent'
      operationId: readAgent
      tags:
        - agents
      responses:
        '200':
          $ref: "#/components/responses/AgentObjRes"
        '400':
          description: Failed due to malformed JSON.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
    put:
      parameters:
        - $ref: "#/components/parameters/Authorization"
      summary: 'Update an existing Agent'
      operationId: updateAgent
      tags:
        - agents
      requestBody:
        required: true
        $ref: "#/components/requestBodies/AgentUpdateReq"
      responses:
        '200':
          $ref: "#/components/responses/AgentObjRes"
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '422':
          description: Database can't process request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
    delete:
      parameters:
        - $ref: "#/components/parameters/Authorization"
      summary: 'Delete an existing Agent'
      operationId: deleteAgent
      tags:
        - agents
      responses:
        '204':
          description: Agent removed.
        '400':
          description: Failed due to malformed Agent ID.
        '401':
          description: Missing or invalid access token provided.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agents/{id}/matching_groups:
    parameters:
      - $ref: "#/components/parameters/Authorization"
      - $ref: "#/components/parameters/AgentId"
    get:
      summary: 'Get matching groups for an existing Agent'
      operationId: matchingGroups
      tags:
        - agents
      responses:
        '200':
          $ref: "#/components/responses/AgentMatchingGroupsObjRes"
        '400':
          description: Failed due to malformed JSON.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agents/validate:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    post:
      summary: 'Validate an Agent configuration without saving it'
      operationId: validateAgent
      tags:
        - agents
      requestBody:
        $ref: "#/components/requestBodies/AgentCreateReq"
      responses:
        '200':
          $ref: "#/components/responses/AgentValidateObjRes"
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '415':
          description: Missing or invalid content type.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agents/backends:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    get:
      summary: 'List of Agent backends'
      operationId: listAgentsBackends
      tags:
        - agents
      responses:
        '200':
          $ref: "#/components/responses/AgentBackendsObjRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agents/backends/pktvisor/taps:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    get:
      summary: 'List of pktvisor Taps available from current agents'
      operationId: listTaps
      tags:
        - agents
      responses:
        '200':
          $ref: "#/components/responses/pktvisorTapsObjRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agents/backends/pktvisor/inputs:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    get:
      summary: 'List of pktvisor Inputs available across current agents'
      operationId: listInputs
      tags:
        - agents
      responses:
        '200':
          $ref: "#/components/responses/pktvisorInputsObjRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agents/backends/pktvisor/handlers:
    parameters:
      - $ref: "#/components/parameters/Authorization"
    get:
      summary: 'List of pktvisor Handlers available across current agents'
      operationId: listHandlers
      tags:
        - agents
      responses:
        '200':
          $ref: "#/components/responses/pktvisorHandlersObjRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"
  /agent/{id}/rpc/reset:
    parameters:
      - $ref: "#/components/parameters/Authorization"
      - $ref: "#/components/parameters/AgentId"
    post:
      summary: 'Request for reset agent remotely'
      operationId: resetAgent
      tags:
        - agents
      responses:
        '200':
          description: Agent was successful resquested to reset
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: A non-existent entity request.
        '500':
          $ref: "#/components/responses/ServiceErrorRes"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  requestBodies:
    AgentGroupCreateReq:
      description: JSON-formatted document describing the new Agent Group configuration
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentGroupCreateReqSchema"
    AgentGroupUpdateReq:
      description: JSON-formatted document describing the updated Agent Group configuration
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentGroupUpdateReqSchema"
    AgentCreateReq:
      description: JSON-formatted document describing the new Agent configuration
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentCreateReqSchema"
    AgentUpdateReq:
      description: JSON-formatted document describing the updated Agent configuration
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentUpdateReqSchema"
  parameters:
    Name:
      name: name
      description: Name filter. Filtering is performed as a case-insensitive partial match.
      in: query
      schema:
        type: string
      required: false
    Order:
      name: order
      description: Order type.
      in: query
      schema:
        type: string
        default: id
        enum:
          - name
          - id
      required: false
    Direction:
      name: dir
      description: Order direction.
      in: query
      schema:
        type: string
        default: desc
        enum:
          - asc
          - desc
      required: false
    Limit:
      name: limit
      description: Size of the subset to retrieve.
      in: query
      schema:
        type: integer
        default: 10
        maximum: 100
        minimum: 1
      required: false
    Offset:
      name: offset
      description: Number of items to skip during retrieval.
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
      required: false
    Tags:
      name: tags
      description: Tags filter. Filtering is performed as a case-insensitive partial key value match.
      in: query
      schema:
        type: object
        example: "{\"key\":\"value\"}"
      required: false
    Authorization:
      name: Authorization
      description: User's access token (bearer auth)
      in: header
      bearerAuth:
        scheme: bearer
        type: http
        format: JWT
      required: true
    AgentGroupId:
      name: id
      description: Unique Agent Group identifier.
      in: path
      schema:
        type: string
        format: uuid
      required: true
    AgentId:
      name: id
      description: Unique Agent identifier.
      in: path
      schema:
        type: string
        format: uuid
      required: true
  responses:
    AgentGroupObjRes:
      description: Agent Group object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentGroupsObjSchema"
    AgentGroupValidateObjRes:
      description: Agent Group object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentGroupsValidateObjSchema"
    AgentGroupsPageRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentGroupPageSchema"
    AgentObjRes:
      description: Agent object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentObjSchema"
    AgentMatchingGroupsObjRes:
      description: Agent Matching Groups object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentMatchingGroupsObjSchema"
    AgentValidateObjRes:
      description: Agent validation object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentValidateObjSchema"
    AgentPageRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentPageSchema"
    AgentBackendsObjRes:
      description: List of Agent backends object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentBackendsObjSchema"
    pktvisorTapsObjRes:
      description: list of pktvisor Taps available from current agents
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PktvisorTapsObjSchema"
    pktvisorInputsObjRes:
      description: list of pktvisor Inputs available from current agents
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PktvisorInputsObjSchema"
    pktvisorHandlersObjRes:
      description: list of pktvisor Handlers available across current agents
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PktvisorHandlersObjSchema"
    ServiceErrorRes:
      description: Unexpected server-side error occurred.
      content:
        application/json:
          schema:
            type: string
            format: byte
  schemas:
    AgentGroupUpdateReqSchema:
      type: object
      properties:
        name:
          type: string
          description: A unique name label
          example: eu-agents
        description:
          type: string
          description: User description of this Agent Group
          example: An example agent group representing european dns nodes
        tags:
          type: object
          description: User defined key/values that will define the members of the group by matching against Agent tags
          example:
            region: eu
            node_type: dns
    AgentGroupCreateReqSchema:
      type: object
      required:
        - name
        - tags
      properties:
        name:
          type: string
          description: A unique name label
          example: eu-agents
        description:
          type: string
          description: User description of this Agent Group
          example: An example agent group representing european dns nodes
        tags:
          type: object
          description: User defined key/values that will define the members of the group by matching against Agent tags
          example:
            region: eu
            node_type: dns
    AgentGroupPageSchema:
      type: object
      properties:
        agent_groups:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/AgentGroupsObjSchema"
        total:
          type: integer
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          description: Maximum number of items to return in one page.
      required:
        - agent_groups
    AgentUpdateReqSchema:
      type: object
      properties:
        name:
          type: string
          description: A unique name label
          example: my-agent1
        orb_tags:
          type: object
          description: User defined key/values that will define the members of the group by matching against Agent tags
          example:
            region: eu
            node_type: dns
    AgentCreateReqSchema:
      type: object
      required:
        - name
        - tags
      properties:
        name:
          type: string
          description: A unique name label
          example: my-agent1
        orb_tags:
          type: object
          description: User defined key/values that will define the members of the group by matching against Agent tags
          example:
            region: eu
            node_type: dns
    AgentPageSchema:
      type: object
      properties:
        agents:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/AgentObjSchema"
        total:
          type: integer
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          description: Maximum number of items to return in one page.
      required:
        - agents
    ConfigEntrySchema:
      type: object
      properties:
        title:
          type: string
          description: Visual title of the config item shown in UI
        type:
          type: string
          description: "Data field type"
          enum:
            - string
            - password
            - int
        name:
          type: string
          description: The field label used in the JSON config object for this field
        description:
          type: string
          description: A description of the use of this configuration field
      example:
        title: Remote Host
        type: string
        name: remote_host
        description: The remote host to send Prometheus metrics too
    AgentGroupsObjSchema:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier (UUID)
        name:
          type: string
          description: A unique name label
          example: eu-agents
        description:
          type: string
          description: User description of this Agent Group
          example: An example agent group representing european dns nodes
        tags:
          type: object
          description: User defined key/values that will define the members of the group by matching against Agent tags
          example:
            region: eu
            node_type: dns
        ts_created:
          type: string
          format: date-time
          description: Timestamp of creation
        matching_agents:
          type: object
          description: Counts of agents currently matching this group
          properties:
            total:
              type: integer
              description: total agents matching
            online:
              type: integer
              description: total agents matching which are currently online
    AgentGroupsValidateObjSchema:
      type: object
      properties:
        name:
          type: string
          description: A unique name label
          example: eu-agents
        tags:
          type: object
          description: User defined key/values that will define the members of the group by matching against Agent tags
          example:
            region: eu
            node_type: dns
        matching_agents:
          type: object
          description: Counts of agents currently matching this group
          properties:
            total:
              type: integer
              description: total agents matching
            online:
              type: integer
              description: total agents matching which are currently online
    AgentObjSchema:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier (UUID)
        name:
          type: string
          description: A unique name label
          example: my-agent1
        agent_tags:
          type: object
          description: Orb tags field sent in by the agent when it connects group by matching against Agent tags
          example:
            region: eu
            node_type: dns
        orb_tags:
          type: object
          description: Orb tags field defined through the API or UI
          example:
            region: eu
            node_type: dns
        ts_created:
          type: string
          format: date-time
          description: Timestamp of creation
        agent_metadata:
          type: object
          description: JSON object sent in by the agent representing its Capabilities
          example:
            region: eu
            node_type: dns
        state:
          type: string
          description: Current connection status of the agent, one of 'new', 'online', 'offline', 'stale', 'removed'
          example: 'online'
        last_hb_data:
          type: object
          description: JSON object sent in by the agent as its last heartbeat
        ts_last_hb:
          type: string
          format: date-time
          description: A time stamp of the last heartbeat that was received
        key:
          type: string
          format: uuid
          description: Agent key is a secret key that is generated at agent creation for authentication purposes
        channel_id:
          type: string
          format: uuid
          description: Communication channel ID (UUIDv4), unique to this agent and created at agent creation
    AgentMatchingGroupsObjSchema:
      type: array
      items:
        type: object
        properties:
          group_id:
            type: string
            format: uuid
            description: group id
          name:
            type: string
            description: group name
            example: 'group-1'
    AgentValidateObjSchema:
      type: object
      required:
        - id
      properties:
        name:
          type: string
          description: A unique name label
          example: my-agent1
        orb_tags:
          type: object
          description: Orb tags field sent in by the agent when it connects group by matching against Agent tags
          example:
            region: eu
            node_type: dns
    AgentBackendsObjSchema:
      type: array
      items:
        type: object
        properties:
          backend:
            type: string
            description: avaliable backend name
            example: pktvisor
          description:
            type: string
            description: Description of this backend
            example: pktvisor observability agent from pktvisor.dev
          schema_version:
            type: string
            description: Version of the schema for this Backend
            example: '1.0'
    PktvisorTapsObjSchema:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            description: avaliable tap name
            example: anycast_dns
          input_type:
            type: string
            example: pcap
          config_predefined:
            type: array
            items:
              type: string
              example: iface
          agents:
            type: object
            properties:
              total:
                type: integer
    PktvisorInputsObjSchema:
      required:
        - iface
      type: object
      properties:
        pcap:
          type: object
          description: input type
          properties:
            filter:
              type: object
              properties:
                bpf:
                  type: string
                  description: tcpdump compatible filter expression for limiting the traffic examined (with BPF)
            config:
              type: object
              properties:
                iface:
                  type: string
                  description: The network interface to capture traffic from
                  example: eth0
            host_spec:
              type: string
              description: Subnets (comma separated) which should be considered belonging to this host, in CIDR form. Used for ingress/egress determination, defaults to host attached to the network interface
              example: 10.0.1.0/24,10.0.2.1/32,2001:db8::/64
            pcap_source:
              type: string
              description: Packet capture engine to use. Defaults to best for platform
              example: libpcap
          additionalProperties:
            type: string
            description: Input version
      example:
        pcap:
          "1.0":
            filter:
              bpf: udp port 53 and host 127.0.0.1
            config:
              iface: eth0
            host_spec: 10.0.1.0/24,10.0.2.1/32,2001:db8::/64
            pcap_source: libpcap

    PktvisorHandlersObjSchema:
      type: object
      properties:
        additionalProperties:
          type: object
          properties:
            version:
              type: integer